Programming With QuickTime VR 2.1
The QuickTime VR Manager function QTVRGetNodeInfo (QTVRGetNodeInfo) returns the node information atom container that describes a node and all the hot spots in the node. One of the atoms in a node information atom container is a node header atom, which contains the type and ID of the node, as well as the node name and any node comments. You can use standard QuickTime atom container functions to retrieve the information in a node header atom. For example, the MyGetNodeName function defined in Listing 3 returns the name of a node, given its node ID.
The structure of a node header atom is described in "Node Header Atom Structure," .
Listing 3 Getting a node's name
OSErr MyGetNodeName (QTVRInstance theInstance, UInt32 theNodeID,
StringPtr theStringPtr)
{
OSErr theErr = noErr;
QTAtomContainer theNodeInfo;
VRNodeHeaderAtomPtr theNodeHeader;
QTAtom theNodeHeaderAtom = 0;
//Get the node information atom container.
theErr = QTVRGetNodeInfo(theInstance, theNodeID, &theNodeInfo);
//Get the node header atom.
if (!theErr)
theNodeHeaderAtom = QTFindChildByID(theNodeInfo, kParentAtomIsContainer,
kQTVRNodeHeaderAtomType, 1, nil);
if (theNodeHeaderAtom != 0) {
QTLockContainer(theNodeInfo);
//Get a pointer to the node header atom data.
theErr = QTGetAtomDataPtr(theNodeInfo, theNodeHeaderAtom, nil,
(Ptr *)&theNodeHeader);
//See if there is a name atom.
if (!theErr && theNodeHeader->nameAtomID != 0) {
QTAtom theNameAtom;
theNameAtom = QTFindChildByID(theNodeInfo, kParentAtomIsContainer,
kQTVRStringAtomType, theNodeHeader->nameAtomID, nil);
if (theNameAtom != 0) {
VRStringAtomPtr theStringAtomPtr;
//Get a pointer to the name atom data; copy it into the string.
theErr = QTGetAtomDataPtr(theNodeInfo, theNameAtom, nil,
(Ptr *)&theStringAtomPtr);
if (!theErr) {
short theLen = theStringAtomPtr->stringLength;
if (theLen > 255)
theLen = 255;
BlockMove(theStringAtomPtr->string, &theStringPtr[1], theLen);
theStringPtr[0] = theLen;
}
}
}
QTUnlockContainer(theNodeInfo);
}
QTDisposeAtomContainer(theNodeInfo);
return(theErr);
}
The MyGetNodeName function defined in Listing 3 retrieves the node information atom container (by calling QTVRGetNodeInfo ) and then looks inside that container for a node header atom with atom ID 1. If it finds one, it locks the container and then gets a pointer to the node header atom data. The format of this data is defined by the VRNodeHeaderAtom data structure:
typedef struct VRNodeHeaderAtom {
UInt16 majorVersion;
UInt16 minorVersion;
OSType nodeType;
QTAtomID nodeID;
QTAtomID nameAtomID;
QTAtomID commentAtomID;
UInt32 reserved1;
UInt32 reserved2;
} VRNodeHeaderAtom, *VRNodeHeaderAtomPtr;
The desired information, the node name, is contained in the string atom whose atom ID is specified by the nameAtomID field of this structure. Accordingly, the MyGetNodeName function then calls QTFindChildByID once again to find that string atom. If the string atom is found, MyGetNodeName calls QTGetAtomDataPtr to get a pointer to the string atom data. A string atom has this structure:
typedef struct VRStringAtom {
UInt16 stringUsage;
UInt16 stringLength;
unsigned char theString[4];
} VRStringAtom, *VRStringAtomPtr;
Finally, MyGetNodeName copies the string data into the appropriate location and cleans up after itself before returning.